vergen - Emit cargo instructions from a build script
vergen
, when used in conjunction with cargo build scripts can emit the following:
- Will emit
cargo:rustc-env=VAR=VALUE
for each feature you have enabled. These can be referenced with theenv!
macro in your code. - Will emit
cargo:rerun-if-changed=.git/HEAD
if the git feature is enabled. This is done to ensure any git instructions are regenerated when commits are made. - Will emit
cargo:rerun-if-changed=.git/<path_to_ref>
if the git feature is enabled. This is done to ensure any git instructions are regenerated when commits are made. - Can emit
cargo:warning
outputs if thefail_on_error
feature is not enabled and the requested variable is defaulted through error or theidempotent
flag. - Will emit
cargo:rerun-if-changed=build.rs
to rerun instruction emission if thebuild.rs
file changed. - Will emit
cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
to rerun instruction emission if theVERGEN_IDEMPOTENT
environment variable has changed. - Will emit
cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
to rerun instruction emission if theSOURCE_DATE_EPOCH
environment variable has changed.
Current Release
MSRV
The current minimum supported rust version is 1.70.0
Example Usage
See the documentation at docs.rs for example usage
Cargo
feature unification for vergen
versions prior to 8.3.0
When a dependency is used by multiple packages, Cargo will use the union of all features enabled on that dependency when building it. Prior to version 8.3.0, vergen
had a set of mutually exclusive features gitcl
, git2
, and gitoxide
to enable to specific git backend you wished to use. If your crate has a dependency on another crate that uses vergen
, your crate may fail to compile if you select a different git
backend then the crate you depend on. For example, your crate depends on fancy-lib
.
fancy-lib Cargo.toml
[]
= { = "8.2.10", = ["git","gitcl"] }
your crate Cargo.toml
[]
= "0.1.0"
[]
= { = "8.2.10", = ["git","gitoxide"] }
Your crate will fail to compile because cargo
unifies this to
= { = "8.2.10", = ["git","gitcl","gitoxide"] }
and prior to 8.3.0 vergen
will not compile with both gitcl
and gitoxide
as features.
As a workaround, you can use cargo tree -f "{p} {f}" | grep vergen
to determine the feature list cargo has set for vergen
. If
a git
backend has already been determined you will be able to use that without declaring those features in your dependency list. This is not perfect as this leaves you at the mercy of your dependency and the git feature they selected, but it's a workaround until version 9 comes out.
fancy-lib Cargo.toml
[]
= { = "8.2.10", = ["git","gitcl"] }
your crate Cargo.toml
[]
= "0.1.0"
[]
= "8.2.10"
Unified
= { = "8.2.10", = ["git","gitcl"] }
Cargo
feature unification for vergen
versions 8.3.0 and beyond
vergen
will accept gitcl
,git2
, and gitoxide
as features. If more than one of them is included, vergen
will select gitcl
before git2
and git2
before gitoxide
.
Notes about the optional git2
dependency
git2
picked up some security related features. In docker environments especially, this requires a safe.directory
configuration. There are a couple methods for achieving this.
- If you control the build, you can add
git config --global --add safe.directory /workspace
to the build file. - If you do not control the docker build, you can add
git config --global --add safe.directory /workspace &&
before the actual command you are running when using docker run. - If you do not control the docker build, you can mount a
.gitconfig
file at/root
that includes thesafe.directory
configuration. I use this method myself when building static binaries with clux/muslrust.
docker run -v cargo-cache:/root/.cargo/registry -v (pwd):/volume -v ~/.gitconfig:/root/.gitconfig:ro --rm -t clux/muslrust:stable cargo build --release
See https://github.com/rustyhorde/vergen/pull/126 for more discussion on the topic. If the solutions above do not work for your usecase, you can pin your vergen
version to 7.4.3, with the caveat you will be exposed to the issues described at the link above.
Contributing
See the documentation at CONTRIBUTING.md
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.